.\" $Id: PAPI_get_thr_specific.3,v 1.6 2004/09/30 17:08:25 london Exp $
.TH PAPI_get_thr_specific 3 "September, 2004" "PAPI Programmer's Reference" "PAPI"

.SH NAME
PAPI_get_thr_specific, PAPI_set_thr_specific \- Store or retrieve a pointer to a thread specific data structure

.SH SYNOPSIS
.nf
.B #include <papi.h>
.BI "int PAPI_get_thr_specific(int tag, void **ptr);"
.BI "int PAPI_set_thr_specific(int tag, void *ptr);"
.fi

.SH DESCRIPTION
In C, PAPI_set_thr_specific will save ptr into an array indexed by tag.
PAPI_get_thr_specific will retrieve the pointer from the array with index tag.
There are 2 user available locations and tag can be either PAPI_USR1_TLS
or PAPI_USR2_TLS.  The array mentioned above is managed by PAPI and 
allocated to each thread which has called PAPI_thread_init. There are no 
Fortran equivalent functions.

.SH ARGUMENTS
.LP
.I tag
--  An identifier, the value of which is either PAPI_USR1_TLS or
PAPI_USR2_TLS. This identifier indicates which of several data structures 
associated with this thread is to be accessed.
.LP
.I ptr
--  A pointer to the memory containing the data structure.

.SH RETURN VALUES
On success, this function returns 
.B PAPI_OK.
 On error, a negative error value is returned.

.SH ERRORS
.TP
.B "PAPI_EINVAL"
The 
.I tag 
argument is out of range.

.SH EXAMPLE
.LP
.nf
.if t .ft CW
   HighLevelInfo *state = NULL;

   if (retval = PAPI_thread_init(pthread_self) != PAPI_OK)
      handle_error(retval);

   /*
    * Do we have the thread specific data setup yet?
    */
   if ((retval = PAPI_get_thr_specific(PAPI_USR1_TLS, (void *) &state))
       != PAPI_OK || state == NULL) {
      state = (HighLevelInfo *) malloc(sizeof(HighLevelInfo));
      if (state == NULL)
         return (PAPI_ESYS);

      memset(state, 0, sizeof(HighLevelInfo));
      state->EventSet = PAPI_NULL;

      if ((retval = PAPI_create_eventset(&state->EventSet)) != PAPI_OK)
         return (PAPI_ESYS);

      if ((retval=PAPI_set_thr_specific(PAPI_USR1_TLS, state))!=PAPI_OK)
         return (retval);
   }

.if t .ft P
.fi

.SH BUGS
There are no known bugs in these functions.

.SH SEE ALSO
.BR PAPI_thread_init "(3), .BR PAPI_thread_id "(3), "
.BR PAPI_register_thread "(3)" 
